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Intellectual Property Rights 



IPRs essential or potentially essential to the present document may have been declared to ETSI. The information 
pertaining to these essential IPRs, if any, is publicly available for ETSI members and non-members, and can be found 
in ETSI SR 000 314: "Intellectual Property Rights (IPRs); Essential, or potentially Essential, IPRs notified to ETSI in 
respect of ETSI standards", which is available from the ETSI Secretariat. Latest updates are available on the ETSI Web 
server ( http://ipr.etsi.org ). 

Pursuant to the ETSI IPR Policy, no investigation, including IPR searches, has been carried out by ETSI. No guarantee 
can be given as to the existence of other IPRs not referenced in ETSI SR 000 314 (or the updates on the ETSI Web 
server) which are, or may be, or may become, essential to the present document. 



Foreword 

This Technical Specification (TS) has been produced by ETSI Technical Committee Smart Card Platform (SCP). 

The contents of the present document are subject to continuing work within TC SCP and may change following formal 
TC SCP approval. If TC SCP modifies the contents of the present document, it will then be republished by ETSI with 
an identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

early working draft; 

1 presented to TC SCP for information; 

2 presented to TC SCP for approval; 

3 or greater indicates TC SCP approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 
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Scope 



The present document defines an Application Programming Interface for the Java Card^^ to use transport protocols 
(e.g. CAT_TP as defined in TS 102 127 [1]) for CAT applications. 

This stage 2 document describes the interface functionalities, the interface working mechanisms and its information 
flow. 



2 References 

References are either specific (identified by date of publication and/or edition number or version number) or 
non-specific. For specific references, only the cited version applies. For non-specific references, the latest version of the 
reference document (including any amendments) applies. 

Referenced documents which are not found to be publicly available in the expected location might be found at 
http://docbox.etsi.org/Reference . 

NOTE: While any hyperlinks included in this clause were valid at the time of publication, ETSI cannot guarantee 
their long term validity. 



2.1 



Normative references 



The following referenced documents are necessary for the application of the present document. 

[1] ETSI TS 102 127: "Smart Cards; Transport protocol for CAT apphcations; Stage 2 (Release 6)". 

[2] Sun Microsystems Java Card^^ Specification: "Java CardTM 2.2.2 Virtual Machine 

Specification". 

NOTE: SUN Java Card Specifications can be downloaded at http://iava.sun.com/products/iavacard . 

[3] ETSI TS 101 220: "Smart Cards; ETSI numbering system for telecommunication application 

providers". 

[4] ETSI TS 102 223: "Smart Cards; Card AppHcation Toolkit (CAT)". 

[5] "GlobalPlatform Card Specification Version 2.2, Amendment B" Version 1.1. 

NOTE: See http://www. globalplatform.org/ . 



[6] 



[7] 



ETSI TS 102 483: "Smart cards; UICC-Terminal interface; Internet Protocol connectivity between 
UICC and terminal". 

ETSI TS 102 225: "Smart cards; Secured packet structure for UICC based applications". 



2.2 



Informative references 



The following referenced documents are not necessary for the application of the present document but they assist the 
user with regard to a particular subject area. 



[i.l] 


Void, 


[i.2] 


Void, 


[i.3] 


Void, 


[i.4] 


Void, 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the following terms and definitions apply: 

BIPLink: interface to access the physical layer by means of the Bearer Independent Protocol according to 

TS 102 223 [4] 

transport layer: instance within the card framework which implements the transport protocol, e.g. CAT_TP 

3.2 Abbreviations 

For the purposes of the present document, the following abbreviations apply: 



ACK 


ACKnowledge 


AID 


Application IDentifier 


API 


Application Programming Interface 


BIP 


Bearer Independent Protocol 


NOTE: 


See TS 102 223 [4]. 


CAT 


Card Apphcation Toolkit 


NOTE: 


SeeTS 102 223 [4]. 


CAT_TP 


Card Application Toolkit Transport Protocol 


NOTE: 


SeeTS 102 127[1]. 


FFS 


For Further Study 


HTTP 


HyperText Transfer Protocol 


IP 


Internet Protocol 


JCRE 


Java Card''"*^ Runtime Environment 


SCP81 


Secure Channel Protocol '81' 


NOTE: 


See "GlobalPlatform Card Specification Version 2.2 


sews 


Smart Card Web Server 


TCP 


Transmission Control Protocol 



Overall description 



The present document describes an API that provides applications a set of Connection Oriented Services. This API 
provides either direct access to the transport protocols supported by the terminal (by using the BIP) or access to 
transport protocol layers provided by the UICC, e.g. the CAT_TP protocol layer in the UICC or SCP81. 



4.1 Connection API concept 



The API is based on the concept of objects that encapsulate the features of connection service (e.g. opening a service, 
sending and receiving data, etc.). 

The present document provides three variants of connection services to the application. These variants are based on the 
Connection interface which is an abstraction of the BIP channel which is used to exchange data. 

One type of connection service is accessible through the BIPLink interface. It provides direct access to the transport 
protocol stack in the terminal. Another type of connection is accessible via the UICCTransportLink interface. It 
provides an interface to a transport protocol layer deployed on the UICC, e.g. CAT_TP. The transport protocol layer on 



£75/ 



Release 1 1 7 ETSI TS 1 02 267 V1 1 .0.0 (201 2-1 2) 

the UICC uses BIP to transport its PDU to the terminal. The last type of connection is accessible through the 
SCP81 Connection interface. It provides an interface to a transport protocol layer based on SCP81 as defined in [5]. 

Implementations of BIPLink interface and UICCTransportLink interface are based on the Observer design pattern. 
I.e. the application is notified about state changes (e.g. data received, channel closed, etc.) by means of events sent to 
the Observer interface. 

The support of each type of connection is optional. If a type of connection is not supported, the related method in the 
ConnectionServer class shall throw a ConnectionException with reason code 
TRANSPORT PROTOCOL NOT SUPPORTED. 



5 API architecture 

For a reference documentation of all classes and interfaces of the Connection oriented Services API refer to annex A. 

5.1 API usage 

5.1 .1 Establishing a Connection 

To perform operations on a specific link it is required to establish a Connection; a Connection can be considered as a 
pure point to point connection on which a link can be established. 

Depending on the nature of the link, the Connection may be shared among different links or can be used exclusively by 
one link. In case of sharing, all the Connection shall have the same parameters. Even if the links allow to share the same 
Connection, it is possible, at Connection instantiation time, to specify that a Connection cannot be shared among several 
links. 

The Connection may require some specific Toolkit resources to be available to the application, e.g. in case of BIP 
connections, at least one BIP channel must be available to the application when the Connection is opened. 
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5.1.2 Opening a BIPLink 



A BIPLink requires the usage of an underlying Connection to transport data according to the BIP protocol.The used 
Connection must be a BIP connection. 



Applet 



Transport 
Layer 



User 
Equipment 



ConnectionServer.getConneclionO 



ConnectionServer.createBIPLinkO 



BIPLinls.^ 

BIPLink.OpenO 



OPEN CHANNEL 



TERMINAL RESPONSE 



Server 



Figure 1 : Opening a BIPLinl< 
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5.1 .3 Creating an UICC Transport link 



Applet 

I ConnectionServer.getConnection( 



Transport 
Layer 



User Equipement 



Connection 



T 



ConnectionServer.CreateUICCTransportLink(Connection) 

^ 



UlCCTransportLink 



Short:=UICCTransporLink.Connect(.. 



Open Channel (UDP Parameters) 



Terminal Response 



Send Data(SYN) 



Terminal Response 



I 



Envelope(Event download - data available 



Receive Data 



Terminal Response(SYN-ACK) 



Send Data(ACK) 



Terminal Response 



UlCCTranspor Link Open 



T 



Figure 2: Creating a reliable link 



Server 



SYN 



SYN-ACK 



ACK 



The API is considered as a blocking API which means that no other applet is able to use the 

uicc.toolkit.ProactiveHandler while the call to the method UICCTransportLink.connect() is ongoing, i.e. the three way 
handshake is performed. 
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5.1 .4 Sending data over UICC Transport Link 




Transport 
Layer 



l)oolean=UICCTransportLink.sendSDU{. .) 




Figure 3: Sending data over Reliable Link 

No other applet is able to use the uicc.toolkit.ProactiveHandler while the call to the method 
UICCTransportLink.sendSDU{. ) is ongoing, i.e. that each PDU has been acknowledged. 

After UICCTransportLink.sendSDU method returns, the uicc.toolkit.ProactiveHandler shall be available to the calling 
applet if it was available before the method invocation; however, handler content may be affected by the system during 
method execution. 
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5.1.5 Receiving data 



Applet 



Transport 
Layer 



User 
Equipment 



Server 



ACK_DATA 



ENVELOPE (Event download - 
data available) 



RECEIVE DATA 



TERMINAL RESPONSE 
(ACK_DATA) 



SEND DATA (ACK) 



ENVELOPE (Event download - 
data available) 



ff- 



eventObserved(DataReceived) 



RECEIVE DATA 



TERMINAL RESPONSE 
(ACK_DATA) 



SEND DATA (ACK) 



ACK 



Figure 4: Receiving data 



Upon reception of an ENVELOPE (Event Download - Data available), the uicc. toolkit. ProactiveHandler is locked by 
the Transport Layer to perform RECEIVE DATA proactive commands; once the terminal indicates that all the available 
data have been received, the uicc. toolkit. ProactiveHandler is released by the Transport Layer to let other apphcations to 
perform proactive commands. 

This behaviour might be affected by other applications, as e.g. a SMS data download which causes a proactive session 
might result in a CAT_TP time-out. 

5.2 Multiplexing through one BIP connection 

If a Connection object has been created with the multiplexingAllowed property, it can be used by several reliable links. 
The Connection status is shared by all ReliableLink objects using it. 
Multiplexing is not allowed for BIPLink objects. 

5.3 Behaviour in duplex communication 
5.3.1 Receiving data while sending data 

Expected behaviour when terminal sends Envelope (Event Download- data available), either on the same BIP channel 
where the sending of data is ongoing or for another BIP channel: 

• The reliable link layer shall receive data and handle the transport protocol (e.g. send ACK). The reliable link 
layer shall not trigger any application on reception of a SDU before the SDU has not been acknowledged. 

• The reliable link protocol implementation (e.g. CAT_TP protocol implementation) handles buffer space by 
adjusting window size for active CAT_TP connections. 
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5.3.2 Sending data while reception of data is ongoing 

In line with the behaviour defined in the previous clause sending while receiving is possible and shall be supported. 

5.3.3 Receiving data of more tlian 1 connection simultaneously 

This shall be supported by the CAT_TP API implementation. 

5.3.4 Sending data before applications returns from DataReceived 

This case shall be allowed. Note that no conflict can occur because the application will not be triggered while a call to 
the blocking ReliableLink.send() method is ongoing. 

5.4 Interference with other proactive commands 

Proactive command (like e.g. Select Item) sent from any application may block the toolkit protocol and thus prevent the 
card from receiving PDUs. This may result in timeouts in the CAT-TP protocol. This behaviour is caused by limitations 
of the Toolkit protocol and cannot be avoided. 

While sending data the CAT_TP layer shall lock the Proactive Handler to avoid that other applications interfere with 
the sending of CAT_TP data. This behaviour is required in order to be able to receive the ACK PDU from the server in 
order to avoid retransmissions. 

5.5 Secured communication based on SCP81 

It is possible for an application to open a connection based on SCP81 to a remote server. The security for data exchange 
is provided by TLS. The HTTP protocol is used on top of TLS to provide encapsulation of the data. 

TCP/IP transport is provided by the Bearer Independent Protocol of TS 102 223 [4] or a direct IP connection as 
specified in TS 102 483 [6]. 

The processing rules for messages that are protected using SCP81 are specified in Amendment B of the Global Platform 
Card Specification v 2.2 [5] and in TS 102 225 [7]. Application data shall be sent in the body part of HTTP POST 
requests and HTTP POST responses. The specialized processing rules for transport of remote APDUs as detailed in 
Amendment B of the Global Platform Card Specification v 2.2 [5] clause 4.3.3, clauses 4.4, 4.5, 4.6, 4.7 and Annex A 
do NOT apply. The following rules apply: 

• The Content-Type header field of the HTTP POST request is set by the card application. 

• The Content-Type header field of the HTTP POST response is set by the remote server. 

• The X-Admin-Script-Status and X-Admin-Targeted-Application headers are meaningless and may be missing. 

• The first request of a session may contain a body if requested by the card application. 

The communication is handled by the entity which implements the SCP81 Connection interface. 

TLS Security is handled by the associated (directly or indirectly) Security Domain of the card application which has 
initiated the SCP81Connection. 

When all headers of an HTTP response have been received by the card, the registered Observer is notified with the 
DataReceived event irrespective of the presence of a body in the HTTP response. The application can read the HTTP 
response with invocation of the non-blocking method DataReceived.copyReceivedData(). The registered Observer is 
also notified when new data has been received belonging to the same HTTP POST response (e.g. transfer coding 
chunked is used). 

It is possible to switch from the protocol described above to RAM/RFM over HTTP or to SCWS remote administration 
protocol as specified in TS 102 225 [7]. 
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NOTE: This switch works only if the applications which handle RAM/RFM over HTTP or SCWS remote 

administration protocol are directly or indirectly associated with the same Security Domain which handles 
the SCP81 secure channel. 

It is not possible to switch from RAM/RFM over HTTP or SCWS remote administration protocol to the one described 
above. 

5.5.1 Sequence diagram 

The following figure presents a sequence diagram describing the SCP81 Connection interface usage. 



Applet/Observer 



Transport 
Layer 



ConnectionServer.createSCP81Connection() 



SCP81 Connection 



SCP81 Connection. open(parameters, 
contentType) 



eventObserved(SCP81ConnectionStatus. 
CONNECTION_ESTABLISHED) 



SCP81 Connection. sendData(data) 



eventObserved(DataReceived) 



DataReceived.copyReceivedDataO 



eventObserved(DataReceived) 



DataReceived.copyReceivedDataO 



SCP81 Connection. closeQ 



eventObserved(SCP81ConnectionStatus. 
CONNECTION_CLOSED) 



Remote 
Server 



PSK-TLS 
Handshake 



POST <URI> HTTP/1.1 

Host: < Host> 

X-Admin-Protocol: giobaipiatform-remote-admin/1 .0 

X-Admin-From; <Agent ID> 

Content- Type; <content-type> 

[Content-Length; xxxx] or 

[Transfer-Encoding: ctiunked] 
[data] 



HTTP/1 .1 200 OK [or HTTP/1 .1 204 No Content] 
X-Admin-Protocoi: giobaipiatform-remote-admin/1. 
[X-Admin-Next-URI: <next-URI>] 
[Content-Type: <content-type> 
[Content-Length; xxxx CRLF] or [Transfer-Encoding; 
chunked CRLF] 
[data...] 



[...data.. 



If chunked mode is used, 
body may be sent in several 
parts. 



CLOSE 



Figure 5: SCP81 Connection sequence diagram 

The remote server behaviour is out of the scope of the present document and is application dependant. 
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Annex A (normative): 
Connection API 



The source files for the uicc. connection package (102267_Annex_A_Java.zip and 102267_Annex_A_HTML.zip) are 
contained in ts_102267vl 10000p0.zip which accompanies the present document. 
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Annex B (normative): 
Connection API identifiers 



The export files for the uicc. connection package (102267_Annex_B_Export_Files.zip) are contained in 
ts_102267vll0000p0.zip which accompanies the present document. 

NOTE: See the "Java Card™ 2.2.2 Virtual Machine Specification" [2]. 
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Annex C (normative): 

Connection API package version management 

Table C.l describes the relationship between each TS 102 267 specification version and its Connection Oriented 
Service API packages AID and Major, Minor versions defined in the export files. 

Table C.1 



TS 102 267 


uicc.connection package 


AID 


Major, 
Minor 




AO 00 GO GO G9 00 05 FF FF FF FF 89 1 5 
GO 00 00 


2.G 



The package AID coding is defined in TS 101 220 [3]. The Connection Oriented Service API package AID is not 
modified by changes to Major or Minor Version. 

The Major Version shall be incremented if a change to the specification introduces byte code incompatibility with the 
previous version. 

The Minor Version shall be incremented if a change to the specification does not introduce byte code incompatibility 
with the previous version. 
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Annex D (informative): 
Change history 

This annex lists all changes made to the present document. 
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